This is part 3 of my NHibernate tutorial, make sure to start from part 1.
Now that we have a mapped model, it’s time to configure the classes that will actually do the hard work. let’s review them:
The Session
The session (more precisely the ISession interface) is our primary API for using NHibernate. It exposes methods for saving, deleting, updating and querying entities. It’s disposable and cheap to create, although deciding when to create or dispose a session is a subject of it’s own, more on which I’ll elaborate later. What’s important to remember for now is that opening a session isn’t equivalent to opening a database connection – the connections are being pooled for us by the session factory, so when we hold a session open an underlying database connection isn’t necessarily being put on hold for us. Also, a session isn’t thread-safe and should be managed accordingly as needed by your application’s architecture (again, more on that later).
The Transaction
NHibernate has it’s own ITransaction interface that doesn’t comply to System.Transactions namespace, for better or worse. managing the transaction goes hand in hand with managing the session, after all an atomic unit of work should be wrapped in a single transaction and we perform those actions on our session. I’ll explain a little more later about that, but it’s important to remember that opening a transaction (unlike opening a session) IS blocking a database connection – that’s why we need to make them as atomic as possible.
The Session Factory
The session factory is an object that’s configured once per database at the application initialization. It knows which database we use, what our domain looks like, how to handle cache, etc.. The session factory (as it’s name reflects) is responsible for creating sessions throughout our application, while managing the connection pool to the database. It’s thread safe and should be accessible throughout our application. It’s also very expensive to create, for obvious reasons.
Configuring the session Factory
NHibernate supports built it configuration via xml, an example can be found here. Also, stating with NHibernate 3, NHibernate supports configuration via code using the NHibernate.Cfg.Loquacious namespace, more on that can be found here. As I said before, I rather work with FNH with provides mappings and configuration via code, so from here on that’s what we’ll be focusing on.
Yawn. Let’s write some code.
Using the Server Explorer, create a new database (I’m assuming you have SQL Server express 2008 on your machine):
Create a new Console Application and use Nuget to add a library package reference to FluentNHibernate. Then add an app.config file and add the following text in it:
<connectionStrings>
<add name="DbConnection"
connectionString="Data Source=.\SQLEXPRESS;Initial Catalog=Tutorial;Integrated Security=True;Pooling=False"/>
</connectionStrings>
Now paste the following code to Program.cs:
1: using System;
2: using Entities;
3: using FluentNHibernate.Cfg;
4: using FluentNHibernate.Cfg.Db;
5: using Mapping;
6: using NHibernate;
7: using NHibernate.Cfg;
8: using NHibernate.Tool.hbm2ddl;
9:
10: namespace ConsoleApp
11: { 12: class Program
13: { 14: private static ISessionFactory _sessionFactory;
15:
16: static void Main(string[] args)
17: { 18: Person person;
19:
20: using (ISession session = OpenSession())
21: using (ITransaction tx = session.BeginTransaction())
22: { 23: person = new Person { Name = "Matan" }; 24: session.Save(person);
25: session.Flush();
26: tx.Commit();
27: }
28:
29: using (ISession session = OpenSession())
30: using (ITransaction tx = session.BeginTransaction())
31: { 32: var newPerson = session.Get<Person>(person.Id);
33: Console.WriteLine(newPerson.Name);
34: }
35: }
36:
37: private static ISession OpenSession()
38: { 39: if (_sessionFactory == null)
40: { 41: _sessionFactory = Fluently.Configure()
42: .Database(MsSqlConfiguration.MsSql2008.ShowSql()
43: .ConnectionString(cfg => cfg.FromConnectionStringWithKey("DbConnection"))) 44: .Mappings(cfg => cfg.FluentMappings.AddFromAssemblyOf<StoreMap>())
45: .ExposeConfiguration(AddConfig)
46: .BuildSessionFactory();
47: }
48:
49: return _sessionFactory.OpenSession();
50: }
51:
52: private static void AddConfig(Configuration cfg)
53: { 54: new SchemaExport(cfg).Create(true, true);
55: }
56: }
57: }
Finally, we have some entities flying around! If you run the code you can see the SQL (both DDL and DML) in the output window of your application, also the data should appear in your database.
We created a session factory (on the first session request), opened a session and a transaction and used them to persist a new Person entity. Then we created a new session (and transaction) and queried for a person with a given id. We then print out the new entity’s name to make sure it’s indeed our entity.
Let’s go over the interesting parts again:
1: _sessionFactory = Fluently.Configure()
2: .Database(MsSqlConfiguration.MsSql2008.ShowSql()
3: .ConnectionString(cfg => cfg.FromConnectionStringWithKey("DbConnection"))) 4: .Mappings(cfg => cfg.FluentMappings.AddFromAssemblyOf<StoreMap>())
5: .ExposeConfiguration(AddConfig)
6: .BuildSessionFactory();
We start by FNH’s Fluently.Configure() methods and then use:
- The Database method, used to define that we’re using SQL Server 2008, and supply two other settings:
- ShowSql() - sets NHibernate to print to the default output every SQL command that’s being executed by a session.
- ConnectionString – set to be taken from our app.config under the name “DbConnection”.
- Next, the Mappings method where we point our configuration to our ClassMaps. I chose to use all of the ClassMap’s in the mappings assembly, but you can add them one by one if you’d like. Notice that other than FluentMappings we can also add HbmMappings (read more here) or AutoMappings (read more here), I’d rather use FluentMappings.
- Next, the ExposeConfiguration allows us to perform extra custom configuration on our underlying IConfiguration object just before it becomes an ISessionFactory. We’ll get there soon, but remember that this is where we can add custom NHibernate configuration, such as listeners and interceptors.
- Finally, a call to BuildSessionFactory wraps it all up and gives us an ISessionFactory, ready for work!
Moving on:
1: private static void AddConfig(Configuration cfg)
2: { 3: new SchemaExport(cfg).Create(true, true);
4: }
As I said, this is our chance to add our custom configuration to the session factory. I’m using a SchemaExport object to tell the session factory that it should generate and export the SQL’s DDL commands upon initialization. Important Note – Some systems use NHibernate to map an existing database, while others create a brand new one for a new system – while SchemaExport is obviously very useful in the development process, you should still manually export changes to your integration and production environments – be careful not to use SchemaExport on a database you DON’T WANT TO DROP.
Lastly:
1: using (ISession session = OpenSession())
2: using (ITransaction tx = session.BeginTransaction())
3: { 4: person = new Person { Name = "Matan" }; 5: session.Save(person);
6: session.Flush();
7: tx.Commit();
8: }
We use the session factory’s OpenSession method to start a new session, we that use the session to explicitly begin a new transaction. If I hadn’t opened a transaction explicitly, the session would have opened one implicitly and committed it when required. Keep in mind that once you open a transaction, unless you commit it yourself it’ll be rolled-back. The session.Flush method isn’t required here since it precedes a commit and that would have triggered a flush automatically, but remember that:
- The session will try to make the minimum possible database requests to achieve maximum efficiency. When using Session.Save you only add your entity to the session’s list of references (AKA first level cache), the actual insert command will only be executed when a flush is called (either by the user or by the active transaction). UNLESS… we use a database mechanism to generate primary keys (such as SQL Server’s Identity or Oracle’s sequence) which forces our session to go directly to the database on every Save command – not very efficient, is it? There are better ways, read more here. But let’s keep it simple for now.
- The database understand transactions, and only transactions – even if you only query data. If you won’t open one yourself it’ll be opened implicitly and that may lead to performance issues, running 3 different Get methods without opening a transaction could lead to 3 different transactions. As a best practice, make sure to begin a transaction explicitly and commit it when you’re done with it – even if you only run queries! More on session and transaction management later on.
Well, we now have a session factory that persists our entities using our mappings, but what else can we do with a session? Find out in the next part – Session and Transaction.
