Code Insanity

NCommon 1.1 Beta on github

Ritesh Rao — Mon, 03 May 2010 03:30:42 GMT

Just a quick note… After testing NCommon 1.1 for a couple of weeks I’ve made a beta build available on github. You can download versions for .net 3.5 and 4.0 from here.

Over the next couple of weeks I’ll be shifting focus on providing comprehensive documentation and reference samples.

Unit Of Work implementation in NCommon 1.1

Ritesh Rao — Tue, 06 Apr 2010 00:30:00 GMT

Dislcaimer: This post is going to be long.

The unit of work implementation in 1.0 worked, and worked quite well. There was no real need to refactor it for 1.1, or any major issues with how it worked. But that being said, while adding multi-database support, more on this later, I started to realize some code smells in there. Coupled that with the kind of questions I’ve gotten on clarifications on what UnitOfWork is and why or when to use a UnitOfWorkScope, I went back and took a long and hard look at the current implementation.

Lets start with the questions first…

Q1: How do I start a UnitOfWork?

Okay this should be a simple question to answer, but it isn’t. The reason being there are TWO ways to start a unit of work in NCommon. You can manually start a unit of work by using the static Start method on the UnitOfWork class:

  104 using(var uow = UnitOfWork.Start())
  105 using (var uowTx = uow.BeginTransaction())
  106 {
  107 
  108     //do something here
  109     uow.Flush();
  110     uowTx.Commit();
  111 }

So the Start method would return an implementation of IUnitOfWork instance, which you could then use to start a transaction and do the usual commit / rollback on. The second is to use the UnitOfWorkScope class:

  104 using (var scope = new UnitOfWorkScope())
  105 {
  106     //Do something here...
  107     scope.Commit();
  108 }

So the next question that would always follow is…

Q2: So whats a UnitOfWorkScope? How is it different from a UnitOfWork?

The raison d'etre of UnitOfWorkScope is to allow sharing of a single IUnitOfWork, and by extension the underlying ORM context (DataContext, ObjectContext, ISession, etc.) between different components and not have to pass around IUnitOfWork instances.

The UnitOfWorkScope works along the same lines as a TransactionalScope. When you create a UnitOfWorkScope instance, if a compatible ambient UnitOfWorkScope instance already exists, it participates as a child of the ambient scope’s transaction.

While technically you could achieve atomic transactions by wrapping all unit of work operations around a TransactionalScope, but sharing the same underlying IUnitOfWork context between different components would require you to pass around the IUnitOfWork instances. Naturally, the next question that arises is, why would I want to share IUnitOfWork contexts? Wouldn’t it be easier to let each component start UnitOfWork instances and do their operations, and then once everything is done complete the scope?

Consider the following example:

  103 public class OrdersService
  104 {
  105     private IRepository<Order> _ordersRepository;
  106     private InventoryService _inventoryService;
  107 
  108     public void CreateOrder(ShoppingCart cart)
  109     {
  110         using (var scope = new TransactionScope())
  111         using (var uow = UnitOfWork.Start())
  112         {
  113             var order = new Order();
  114             //Code to create an order from the shopping cart
  115             _ordersRepository.Save(order);
  116             _inventoryService.ReserveItems(order);
  117             uow.TransactionalFlush();
  118         }
  119     }
  120 }
  121 
  122 public class InventoryService : IInventoryService
  123 {
  124     private IRepository<OrderReservation> _reservationRepository;
  125 
  126     public void ReserveItems(Order order)
  127     {
  128         using (var uow = UnitOfWork.Start())
  129         {
  130             //Reserve stock from order items... OrderReservationEntry has an association to Order
  131             var reservationEntry = new OrderReservation(order);
  132             _reservationRepository.Save(reservationEntry); //THIS WILL THROW AN EXCEPTION.
  133             uow.TransactionalFlush();
  134         }
  135     }
  136 }
  137 

The example above, the OrdersService basically creates an order, adds it to it’s order repository and then asks the InventoryService to reserve stock for the order. The InventoryService creates an reservation entry which has an association to an Order instance, which is then saved to an OrderReservation repository.

When adding the reservation entry to the repository, an exception will be thrown. Why? Because the reservation service creates an new instance of IUnitOfWork by calling UnitOfWork.Start(), which internally creates an new context (ObjectContext / DataContext / ISession / whatever…) and the moment the OrderReservation instance is saved, the underlying context is going to puke an exception that the Order instance is already part of another context.

So while using a TransactionScope does give transacitonal atomicity, it doesn’t solve the problem of being able to share the same UnitOfWork instance across multiple components.

Getting rid of confusion. One class to rule them all

So while working on 1.1, I decided to nuke UnitOfWork. There’s no reason why there should be two ways to start a unit of work, and UnitOfWorkScope is a simple API to do so. This means that if you are manually starting and flushing unit of works using UnitOfWork.Start(), when moving to 1.1 there will be a lot of broken code. This is a breaking change!.

This decision was not made lightly though. Deciding on introducing a breaking change is a tough one, and I believe at this stage it is required to reduce the confusion around the unit of work implementation in NCommon.

Multi database support

By far the number one request has been to add multi-db support in NCommon. Now technically there was a way you “could” simulate multi database support in 1.0. In 1.0, all IUnitOfWorkFactory implementations define a registration method that would take in a Func<T> to resolve instances of ISessionFactory (for NH) or ObjectContext (for EF) or DataContext (for L2S), and you could add some context specific code in the Func<T> implementation to return different instances based on context. A simple example below:

   53 NHUnitOfWorkFactory.SetSessionProvider(() =>
   54 {
   55     if (DatabaseContext.Current == "OrdersDatabase")
   56         return Storage.AppStorage.Application.Get<ISessionFactory>("ordersDB").OpenSession();
   57     return Storage.AppStorage.Application.Get<ISessionFactory>("inventioryDB").OpenSession();
   58 });

While this approach would work, it’s not ideal. One the features I wanted to have in NCommon is have the underlying database context be automatically resolved without having to specify which database the code is accessing.

Configuring NCommon for multiple database support:

In 1.1, the new configuration class is used to configure the data providers for NCommon. The static SetXXX static methods are not exposed by IUnitOfWorkFactory implementations anymore. Instead you use the ConfigureData method exposed by the Configure class in NCommon:

   63 NCommon.Configure.Using(container)
   64     .ConfigureData<NHConfiguration>();

The above example uses NHConfiguration to configure the NHibernate data provider for NCommon. Similar configurations for Linq2Sql and EntityFramework exists. The configuration classes provided by each provider expose a single method that allows registering a Func<T> to resolve instances of ISession / DataContext / ObjectContext.

  393 NCommon.Configure.Using(container)
  394     .ConfigureData<NHConfiguration>(x =>
  395         x.WithSessionFactory(() => OrdersDomainFactory)
  396     );

You can then register multiple factories / contexts for multiple databases like so:

  393 NCommon.Configure.Using(container)
  394     .ConfigureData<NHConfiguration>(x =>
  395         x.WithSessionFactory(() => OrdersDomainFactory)
  396          .WithSessionFactory(() => HRDomainFactory)
  397     );

Querying multiple databases:

Once you’ve registered the factories / contexts querying multiple databases is super simple, a concept inspired by NHibernate Burrow.

  343 using (var scope = new UnitOfWorkScope())
  344 {
  345     var savedCustomer = new NHRepository<Customer>()
  346         .Where(x => x.CustomerID == customer.CustomerID)
  347         .First();
  348 
  349     var savedPerson = new NHRepository<SalesPerson>()
  350         .Where(x => x.Id == salesPerson.Id)
  351         .First();
  352 
  353     Assert.That(savedCustomer, Is.Not.Null);
  354     Assert.That(savedPerson, Is.Not.Null);
  355     scope.Commit();
  356 }

In the above example, Customer is part of the orders database, while SalesPerson is part of the HR database. The UnitOfWorkScope will automatically resolve the appropriate context that the repository should use. This will work for all three providers; NHibernate, EntityFramework and Linq2Sql.

Transaction Management in 1.1

In 1.0, the UnitOfWorkScope would create instances of IUnitOfWOrk behind the scenes and then call BeginTransaction and CommitTrasaction, or RollbackTransaction, on the instance directly. In the case of multiple databases, an instance of IUnitOfWork instance is created for each context and BeginTransaction and CommitTransaction/RollbackTransaction is called on each instance during the lifecycle of the UnitOfWorkScope instance.

This is what I would call manual transaction management.

In 1.1 manual transaction management is completely removed. In fact if you take a look at the IUnitOfWork interface now, there will be just one method:

   27 public interface IUnitOfWork : IDisposable
   28 {
   29     /// <summary>
   30     /// Flushes the changes made in the unit of work to the data store.
   31     /// </summary>
   32     void Flush();
   33 }

The reason of removing transactional management from IUnitOfWork is because there already exists a simple way of managing transactions in .Net, the TransactionScope. Using TransactionScope has been a hard decision actually, since it has the tendency to promote the transaction to a DTC transaction, and even though I loath the DTC, there’s no way around it.

The primary reason is when using multiple databases in a UnitOfWorkScope, when using manual transaction management it doesn’t 100% ensure atomicity. Consider the scenario where, while comitting, the CommitTransaction is called on the first IUnitOfWork instance, which succeeds, and while calling Commit on the second IUnitOfWork instance something bad happens. There’s no way to rollback the first transaction as the underlying IDbTransaction has already comitted.

So the solution would have to be to wrap the entire operation inside a TransactionScope instance. Instead of having an implicit expectation that a TransactionScope is wrapping the entire UnitOfWorkScope operation, the UnitOfWorkScope does the right thing and creates a TransactionScope internally and delegates transaction management to it.

That being said, if an ambient transaction already exists, and it is compatible with the IsolationLevel of the UnitOfWorkScope, the TransactionScope instance it creates will participate in the ambient transaction.

While using TransactionScope simplifies transaction management in NCommon, one thing you should be aware of is that transactions could be enlisted in DTC in certain scnearios. If you using NCommon with a single database, the transaction is enlisted with the LTM and it’s never promoted, unless an existing promoted ambient transaction has already started. If you are using multiple databases, chances are the transaction will be promoted to DTC.

Isolation levels and AutoCompleteScope in 1.1

NCommon 1.0 had constructor overloads for UnitOfWorkScope that would allow you to specify the isolation level that the scope should use. Now, I don’t know about anyone else, but I have never seen an application that uses different isolation levels at different places. So the in 1.1, these overloads are gone.

Additionally, you could provide a UnitOfWorkScopeOptions enumeration to specify if UnitOfWorkScope instances should auto complete while disposing, allowing you to skip having to write the statement scope.Complete everywhere. This again is a global wide configuration in my opinion.

To configure these global settings for UnitOfWorkScope instances, you can use the ConfigureUnitOfWork method exposes by the Configure class:

  394 NCommon.Configure.Using(container)
  395     .ConfigureData<NHConfiguration>(x =>
  396         x.WithSessionFactory(() => OrdersDomainFactory)
  397          .WithSessionFactory(() => HRDomainFactory))
  398     .ConfigureUnitOfWork<DefaultUnitOfWorkConfiguration>(x =>
  399         x.WithDefaultIsolation(IsolationLevel.ReadCommitted)
  400         .AutoCompleteScope()
  401     );

In the code snippet above, the default isolation level is set to ReadComitted and scopes are set to auto complete.

The only overload now exposed by the UnitOfWorkScope class is the option to not enlist the UnitOfWorkScope instance in an existing ambient transaction/unit of work and to start a new transaction/unit of work.

Final thoughts

The above changes should reduce some of the complexity around setting up and using NCommon. Check out these changes in the 1.1 branch.

Refactoring Storage in NCommon 1.1

Ritesh Rao — Mon, 05 Apr 2010 22:15:00 GMT

After having used NCommon in a couple of production projects, the one area that I have disliked is the Storage class. The problem with the static Storage factory has been that if a component relies on one of the Storage classes, it becomes a little bit of a pain to write unit tests for such components. Such unit tests would have to know way too much about which storage implementation the component uses and how it uses it. Session storage was a bigger pain, there’s no ideal way to replace a Session storage implementation that relies on an actual HttpSession while testing.

Eventually what I’d end up with is having wrappers around Storage that would be injected into components via the container. After having to write such plumbing code for the nth time, I figured it’s time for a change.

What’s in a name: Storage or State

The first round of refactoring was to get rid of the Storage naming pattern. While working on above said projects with other team members, I was asked countless number of times “So where does Storage store the data?” or “Do I need a database for Storage to work?”. And that would ensure the slow painful process of explaining that Storage is not “really” a persistent store, rather provides an way to maintain different states of an application. State is the keyword here, and instantly light bulbs would light and questions were answered.

Semantically, the name State is a better representation of what the original Storage class did in NCommon anyways. It provided a way to get access to an application’s state, or a sessions state or thread local state. So in 1.1 the root container of state is now called, wait for it… IState

   19 /// <summary>
   20 /// Base IState interface.
   21 /// </summary>
   22 public interface IState
   23 {
   24     /// <summary>
   25     /// Gets the application specific state.
   26     /// </summary>
   27     IApplicationState Application { get; }
   28     /// <summary>
   29     /// Gets the session specific state.
   30     /// </summary>
   31     ISessionState Session { get; }
   32     /// <summary>
   33     /// Gets the cache specific state.
   34     /// </summary>
   35     ICacheState Cache { get; }
   36     /// <summary>
   37     /// Gets the thread local / request local specific state.
   38     /// </summary>
   39     ILocalState Local { get; }
   40 }

IState pretty much exposes the same set of state implementations as the original Storage class; Application, Session, Local and one additional Cache. Now components can have implementations of IState injected via the container, and tests become cleaner because we can easily create subs/mocks of IState.

Each of the different state interfaces expose the same set of methods; Get, Put and Remove. ICacheState exposes additional overloads to Put to allow specifying expiration policies for cache entries.

The default implementation of IApplicationState and ICacheState are quite straightforward. DefaultApplicationState uses the current AppDomain, same as before, while the DefaultCacheState uses the Http runtime cache.

Session State, Local State, WCF and ASP.Net

Originally, NCommon Storage classes did not support WCF at all. Admittedly, I try to stay far away from WCF (topic for another time), so I had completely ignored the fact that there’d be users who would want to use NCommon in WCF services.

1.1 now provides native support for both WCF and ASP.Net. It goes one step further, if the current host is a WCF host and has AspNetCompatabilityRequirements behavior is applied on the current service, and if it the requirement is set to Allowed or Required, then it will automatically switch from using WCF OperationContext / InstanceContext to HttpContext and HttpSession (that is if the ASP.Net pipeline is present).

Configuring state in NCommon:

State in NCommon is pluggable, and that is intentional. I wanted to be able to replace state implementations based on project scenarios, one common one being replacing the default implementation of ICacheState that uses the http runtime cache to use memcached.

You can use the new configuration fluent interface in NCommon, introduced in this post, by using the ConfigureState method exposed by the static Configure class in NCommon. The ConfigureState method expects a type that implements IStateConfiguration which exposes one single method Configure. A default implementation of IStateConfiguration, DefaultStateConfiguration, is provided. This class exposes four methods that you can use to override the default state implementations that NCommon should use:

UseCustomCacheOf<T>()

UseCustomSessionStateOf<T>()

UseCustomLocalStateOf<T>()

UseCustomApplicationStateOf<T>()

Below is an example where the a custom Memcached cache state provider should be used by NCommon for cache state, rather than the default implemenation:

   19 var container = new WindsorContainer();
   20 var containerAdapter = new WindsorContainerAdapter(container);
   21 NCommon.Configure.Using(containerAdapter)
   22     .ConfigureState<DefaultStateConfiguration>(stateConfig =>
   23         stateConfig.UseCustomApplicationStateOf<ICustomAppState>()
   24                   .UseCustomCacheOf<MemCachedState>());
   25 

Breaking changes:

In the 1.1 branch you won’t find the old Storage class anymore. This has been completely removed for now. So you might find that code that referenced Storage no longer compiles. I will add an implementation of Storage that used the new IState classes back, just for backwards compatibility, but I would strong suggest restructuring your components from using the static methods on Storage to have IState implementations injected via the container.

Getting back on the horse

Ritesh Rao — Mon, 05 Apr 2010 05:31:00 GMT

Well it’s been almost a year since my last post, and I guess it’s about time I get back to blogging. I had intended to take a short vacation, which ended up being a long hiatus. I wont go into reasons why, but lets just say I was dealing with some tough personal issues.

Now that a sense of normalcy is back, it’s time to get back into it.

Updates on NCommon

First thing first, NCommon source has moved from Google code to Github. Although a mirror source of NCommon has been available on Github for a while, I’m officially moving the source to Github. There won’t be any more updates to the SVN repository in Google Code.

You can check out the Github repository here.

Over the last couple of weeks I’ve been working on addressing some of the issues with NCommon and have been adding some much needed features. These changes are being made to the 1.1 branch. I’ll go into some of the new features in upcoming posts.

Configuring NCommon in 1.1

Ritesh Rao — Mon, 05 Apr 2010 05:30:00 GMT

One of the changes I made to NCommon in 1.1 was to provide an easy way to configure NCommon’s various services. The approach taken was inspired by MassTransit’s and Caliburn’s configuration API.

To configure NCommon you can use the static Configure class:

    1 /// <summary>
    2 /// Static configuration class that allows configuration of NCommon services.
    3 /// </summary>
    4 public static class Configure
    5 {
    6     /// <summary>
    7     /// Entry point to NCommon configuration.
    8     /// </summary>
    9     /// <param name="containerAdapter">The <see cref="IContainerAdapter"/> instance to use
   10     /// for component registration.</param>
   11     /// <returns>An instance of <see cref="INCommonConfig"/> that can be used to configure
   12     /// NCommon configuration.</returns> 
   13     public static INCommonConfig Using(IContainerAdapter containerAdapter)
   14     {
   15         Guard.Against<ArgumentNullException>(containerAdapter == null,
   16                                              "Expected a non-null IContainerAdapter implementation.");
   17         return new NCommonConfig(containerAdapter);
   18     }
   19 }

The Using method of the Configure class expects an instance of IContainerAdapter . An implementation of IContainerAdapter is basically a IoC container wrapper that exposes a standard contract that NCommon can use to register components with the IoC container of your choice.

Implementations of Castle Windsor, StructureMap, NInject, Unity are already provided. The interface is simple enough to implement for other containers. Below is an example of using Configure with castle windsor:

   18 var container = new WindsorContainer();
   19 var containerAdapter = new WindsorContainerAdapter(container);
   20 NCommon.Configure.Using(containerAdapter)
   21     .ConfigureState<DefaultStateConfiguration>()
   22     .ConfigureData<NHConfiguration>(nhConfiguration => nhConfiguration
   23         .WithSessionFactory(() => nhFactory))
   24     .ConfigureUnitOfWork<DefaultUnitOfWorkConfiguration>(uowConfiguration => uowConfiguration
   25         .AutoCompleteScope()
   26         .WithDefaultIsolation(IsolationLevel.ReadCommitted));

In future posts I’ll go into details on the different configuration options of NCommon.

Visual Studio Theme

Ritesh Rao — Mon, 28 Sep 2009 11:03:04 GMT

I’ve been getting a lot of requests lately to share my Visual Studio theme. Instead of individually replying to everyone, I’m making it available here. Enjoy.

Domain Events pattern in NCommon

Ritesh Rao — Thu, 18 Jun 2009 02:48:44 GMT

Steve Gentile recently directed me to Udi Dahan’s recent post his improvement on the Domain Event pattern, and after reading the post, digesting it and thinking about his approach I have decided to include it into NCommon.

The Domain Event pattern aims to provide a solution for being able to create fully encapsulated domain models. The term fully encapsulated domain models refer to the approach where the entities in your domain model are not bound or depend on external services for any purpose or operation.

A good example for this, although a beaten to death example, is the email sending or rather the notification example. Lets say when an order’s status has changed an email notification has to be sent out to the customer of the order informing them of this status change. My previous approach has been to use the Service Locator pattern to get a service instance of IOrderStatsNotifier and use the IOrderStatusNotifier instance to send out the emails.

Semantically that has always bothered me because the domain entity really should not be informing the notifier that the order’s status has changed, rather it should be the other way around. The Notifier should automatically be able to handle order’s status change and do the necessary. With the Domain Events pattern this becomes ridiculously easy.

If you haven’t read Udi’s post, I’d strongly recommend reading it. Anyways, the implementation of Domain Events pattern in NCommon is almost identical to that shown in Udi’s post. Below is a test from NCommon that shows how the Domain Event pattern can be used:

[Test]
public void registered_handlers_are_executed_when_event_is_raised ()
{
    var mockTest1Handler = MockRepository.GenerateMock<Handles<TestEvent1>>();
    var mockTest2Handler = MockRepository.GenerateMock<Handles<TestEvent2>>();
    var locator = MockRepository.GenerateStub<IServiceLocator>();
 
    locator.Expect(x => x.GetAllInstances<Handles<TestEvent1>>())
           .Return(new[]{mockTest1Handler});
 
    ServiceLocator.SetLocatorProvider(() => locator);
 
    DomainEvent.Raise(new TestEvent1());
    mockTest1Handler.AssertWasCalled(x => x.Handle(null), options => options.IgnoreArguments());
    mockTest2Handler.AssertWasNotCalled(x => x.Handle(null), options => options.IgnoreArguments());
}

The implementation of Domain Events pattern is available in trunk.

FluentNHibernate Mappings: Any

Ritesh Rao — Fri, 15 May 2009 10:00:00 GMT

Recently Oren (Ayende) had a serious of posts on NHibernate mappings and the various options you can configure using Xml mappings. This series of posts takes those examples and shows how you can use FluentNHibernate to configure the same mappings.

This is a companion post for Oren’s post on the <any> mapping in NHibernate, here. I recommend reading his post before venturing forward.

In Fluent NHibernate you can use the ReferencesAny mapping method to output a <any> mapping:

ReferencesAny(mapping => mapping.Payment)
    .EntityTypeColumn("PaymentType")
    .EntityIdentifierColumn("PaymentId")
    .AddMetaValue<CreditCardPayment>("Credit")
    .AddMetaValue<CheckPayment>("Check")
    .IdentityType(identity => typeof(int));

Note: This mapping method at this time is generating the <any> mapping incorrectly. The mapping that is being generated contains <any> before the <Id> element causing NHibernate to complain. I've submitted a patch to fix this behavior, which you can get from here: http://code.google.com/p/fluent-nhibernate/issues/detail?id=228

Note2: ReferencesAny is available in the latest trunk as support for it was added fairly recently. So if you can't seem to find it in the fluent-nhibernate.dll build you are using, get latest from trunk and build it.

The ReferencesAny prety much matches the <any> element. You specify the meta values using the AddMetaValue method, the type column via EntityTypeColumn and the identity column using the EntityIdentifierColumn method.

FluentNHibernate Mappings: Join

Ritesh Rao — Fri, 15 May 2009 00:00:00 GMT

This is a companion post for Oren’s post on the <join> mapping in NHibernate, here. I recommend reading his post before venturing forward.

To create a joined table mapping using FluentNHibernate you need to use the WithTable mapping function and specify the JoinedPart definition:

WithTable("Addresses", join =>
                           {
                               join.Map(prop => prop.StreetAddress1, "StreetAddress1");
                            join.Map(prop => prop.StreetAddress2, "StreetAddress2");
                            join.Map(prop => prop.City, "City");
                            join.Map(prop => prop.State, "State");
                            join.Map(prop => prop.ZipCode, "ZipCode");
                               join.WithKeyColumn("PersonId");
                           });

The WithTable mapping function has two overloads, one just taking in a string parameter and another that takes in a string parameter as well as a action that allows you to configure a JoinPart. The first overload instructs fluent nhibernate to output the table name of the class being mapped, for e.g WithTable("Persons") will generate a mapping: <class name="Person" table="Persons"> element.

The second overload outputs the <join> element in the mapping. Just like mapping a component, the JoinPart allows you to map properties in the class as belonging to another table. The only thing to be aware of here is that you are specifying the column names in the join table for your properties manually.

Now to define the join table as optional, you again need to use the SetAttribute method to output the "optional" attribute since there's no inbuilt way to specify that in the JoinPart. Below is the full mapping:

WithTable("Addresses", join =>
                           {
                               join.Map(prop => prop.StreetAddress1, "StreetAddress1");
                            join.Map(prop => prop.StreetAddress2, "StreetAddress2");
                            join.Map(prop => prop.City, "City");
                            join.Map(prop => prop.State, "State");
                            join.Map(prop => prop.ZipCode, "ZipCode");
                               join.WithKeyColumn("PersonId");
                            join.SetAttribute("optional", "true");
                           });

FluentNHibernate Mappings: One-To-One

Ritesh Rao — Thu, 14 May 2009 10:00:00 GMT

This is a companion post for Oren’s post on the <one-to-one> mapping in NHibernate, here. I recommend reading his post before venturing forward.

In FluentNHibernate one-to-one mappings are achieved by using the HasOne mapping method on the parent and the References method on the child. Below is the mapping for the Person entity that has a one-to-one relationship with an Employee entity:

            HasOne(prop => prop.Employee)

                .PropertyRef(prop => prop.Person);

You can also specify the actual property that HasOne uses to specify the foreign key relationship using the PropertyRef method. The above statement basically creates a mapping instruction that reads “Person has a one-to-one relationship with Employee on the Person property of the Employee entity”.

Similarly, the Employee mappings use the References mapping method to specify the bi-directional part of the relationship. Here’s the full class mapping for Employee:

    public class EmployeeMap : ClassMap<Employee>

        public EmployeeMap()

            WithTable("Employees");

            Id(prop => prop.Id).GeneratedBy.Native();

            Map(prop => prop.Role);

            References(prop => prop.Person)

                .ColumnName("PersonId")

                .FetchType.Select()

                .LazyLoad()

                .Unique();

The References mapping method in EmployeeMap generates a many-to-one mapping to the Person entity. You must add the Unique mapping modifier to instruct that the many-to-one mapping maps to a unique Person instance making it effectively a one-to-one mapping. You’ll also notice that I’ve set the FetchType to Select, this is done so that associated Person instances are lazy loaded when needed.